How to implement an AttributeConverter to support custom types

Take your skills to the next level!

The Persistence Hub is the place to be for every Java developer. It gives you access to all my premium video courses, 2 monthly Q&A calls, monthly coding challenges, a community of like-minded developers, and regular expert sessions.

Join the Persistence Hub!

All JPA implementations, including Hibernate, provide default mappings for a huge set of standard Java classes. You could model the attributes of all your entity classes using those mappings, and you would be able to map all columns of your table model. But this is often not the best fit for your business logic. A mapping to a domain-specific type or any other Java type that adds semantics to your entity attribute is often more helpful. You could, for example, map a column of type varchar to your domain-specific type Name, which extends the standard class String and adds domain-specific validation. Or you could map a 8-digit hexadecimal color code to an object of type java.awt.Color.

JPA’s AttributeConverter interface provides an easy way to define such a mapping. You only need to implement the 2 methods defined by the interface and specify for which entity attributes you want to use the converter. I’ll show you how to do that in this article.

Contents

The general concept of the AttributeConverter is simple. The 2 methods of the AttributeConverter interface define 2 conversions. One that converts the type used for your entity attribute to a type that gets handled by the JDBC driver when inserting or updating a record in the database. And another one that converts the type returned by the JDBC driver when reading a record from the database to the type used as your entity attribute.

Based on this simple concept, the capabilities and limitations of an attribute converter become obvious.

You can use it on all basic attributes mapped to 1 column in your table model and defined by entity classes, mapped superclasses, or embeddable classes.

But the converter can’t handle more complex types, like an entire ElementCollection, a to-many association, or any attribute you want to map to multiple database columns. You can also not use an AttributeConverter on primary key attributes or version attributes. The JPA specification defines a specific handling for those attributes, which could cause conflicts. And attributes that are annotated with @Temporal or @Enumerated are also not supported. That’s because those annotations already define a mapping to a database column. You need to decide if you want to use the AttributeConverter or the other type mapping and only add the corresponding annotations.

The list of situations in which you can’t use an AttributeConverter might seem much longer than the one in which you can use it. But don’t worry, the AttributeConverter is incredibly useful and can handle almost all standard use cases.

Let’s implement an AttributeConverter that converts between an entity attribute of type java.awt.Color and a String containing a 6-digit hex value.

Implementing an AttributeConverter requires a class that implements the javax.persistence.AttributeConverter (JPA 1 & 2) or jakarta.persistence.AttributeConverter (JPA 3) interface. Besides the package name, those 2 interfaces are identical. As you can see in the code snippet, the AttributeConverter interface uses generics. Those are the type of the entity attribute and the type handled by the JDBC driver. In this example, the attribute will be of type Color and the JDBC driver will handle a String.

And you also need to annotate your converter class with JPA’s @Converter annotation. The @Converter annotation tells your persistence provider, e.g., Hibernate, that this is an attribute converter. And you can set its autoApply attribute to true if you want to use this converter for all entity attributes of type Color. If you don’t want to do that, please check the following section, where I show you how to activate the converter for a specific attribute.

The implementation of the AttributeConverter is pretty simple. The interface defines the methods convertToDatabaseColumn and convertToEntityAttribute. Hibernate and any other JPA implementation call these methods to either convert the value of your entity attribute to the type handled by the JDBC driver or vice versa.

You can activate an AttributeConverter in 3 ways:

That’s all you need to do to implement an AttributeConverter that provides a custom type mapping.

After you activate the AttributeConverter for an attribute, your persistence provider uses the converter transparently for all operations that affect that entity attribute. That includes all read and write operations performed for that entity class and all bind parameters compared with that attribute.

You can see that in the following example. It reads a Rectangle entity object with the color white and changes its color to black.

I used Hibernate as my JPA implementation for the following log output and activated my recommended logging configuration for development systems. You can see the executed SQL statements and the messages written by the AttributeConverter implementation in the log file. 

An AttributeConverter provides an easy and portable way to define a custom type mapping. You can use it for all basic attributes you want to map to 1 database column. In this article, I used that to to persist an entity attribute of type java.awt.Color as a 6-digit hex code. But that’s, of course, not the only kind of mapping you can implement. I used it in other articles to improve Hibernate’s standard enum mapping and to map LocalDate and LocalDateTime in older Hibernate versions that didn’t support those types.

As you saw in this article, implementing an AttributeConverter is simple. You only need to implement the AttributeConverter interface with its 2 conversion methods and annotate that class with a @Converter annotation. If you set the autoApply attribute of that annotation to true, your persistence provider will use the converter for all entity attributes of the supported type. If you don’t set that attribute or set it to false, you need to annotate each entity attribute on which you want to use the converter with @Convert and reference your converter implementation.